home *** CD-ROM | disk | FTP | other *** search
/ Aminet 8 / Aminet 8 (1995)(GTI - Schatztruhe)[!][Oct 1995].iso / Aminet / dev / basic / bc.lha / bc / bc.doc < prev    next >
Text File  |  1995-06-12  |  11KB  |  236 lines
  1. lynnjenn@vef.north.net
  2. Enchanted Blade Associates
  3. R.R. 4 Langton, Ontario
  4. N0E 1G0             Canada
  5.  
  6.            ---------------------------------------------------
  7.            bc 1.00 - a command line compiler for Blitz Basic 2
  8.            ---------------------------------------------------
  9.  
  10. ·Abstract·
  11.  
  12. For a long time now, users of Blitz Basic 2 (BB2) have wished they could use
  13. an editor other than TED, the editor that comes with the BB2 package.  This
  14. package, best described as a `hack' (you've been warned), will let you do
  15. it.
  16.  
  17. The bc package consists of a short script that invokes TED and the bbc
  18. program, the program bbc itself which does all the work, and a default
  19. bc.config file for configuration settings for bbc.
  20.  
  21. Invoking bc with appropriate file options will cause a source file to be
  22. either run (like a "Compile/Run") or turned into an executable (like a
  23. "Create File").
  24.  
  25. This should be considered a beta release.
  26.  
  27. It is hoped by the author that the useful life of this program is short,
  28. that is, that a true command line compiler will be put out by Acid soon.
  29.  
  30. ·Installation·
  31.  
  32. The package consists of the files indicated.  The directory next to the
  33. file name is the place where you should copy it (no install script is
  34. included; installation is pretty simple).
  35.  
  36. File      Copy To      Purpose
  37. --------- ------------ ---------------------------------------------------
  38. bc        S:bc         Compiles files by invoking bbc (called by user)
  39. bbc       C:bbc        Takes over TED to perform actual compilation
  40. bc.config S:bc.config  Allows user-control of various bbc settings
  41. bbc.src#?              Source code for the bbc program¹
  42. test.src               A test program (source code) for the bc package
  43. bc.doc                 Documentation for the bc package
  44.  
  45. ---------------
  46.     ¹ Note that according to the licence for this program, a copy of
  47.   any changes you make to the source code that you wish to distribute must
  48.   be sent to Enchanted Blade Associates (this is only so that we can
  49.   distribute a version that incorporates all of the best changes in one
  50.   single package).  We encourage you to improve the program.
  51.  
  52. ·Configuration·
  53.  
  54. If your TED editing screen is not 640 x 200 (i.e. if you are using an
  55. interlaced or PAL screen), you will have to modify certain lines in the
  56. default bc.config file.  The bc.config file contains information on how to
  57. do this.
  58.  
  59. ·Using the Compiler·
  60.  
  61. The bc package consists of two programs.  The only one you will ever use
  62. is "bc".  In fact, bc is not a program but a shell script (a script is
  63. used to make it easy to change certain aspects of the system, such as
  64. where the bbc program is located; there is a better way, but I didn't have
  65. time to throw it in last night, see the source code for more details).
  66. It runs your BB2 editor, telling it to load your source file, and then
  67. starts bbc, passing it your command arguments.  The bbc program then does
  68. the actual work.
  69.  
  70. There are two ways to run the compiler: in "run" mode and in "create" mode.
  71. In "run" mode, your program will be compiled and then run so you can see
  72. the results.  In "create" mode, your program will be turned into an
  73. executable file.
  74.  
  75. The command line syntax of bc is as follows:
  76.  
  77. bc source [executable|run]
  78.  
  79. A source file must be indicated.  If the second argument is "run", then the
  80. program will be compiled in "run" mode.  Otherwise, the second argument is
  81. the file name for the executable in "create" mode.  If no second argument
  82. is given, the program is run in "create" mode using a file name created by
  83. removing the extension from the source file name (e.g. "code.bb2" becomes
  84. "code").
  85.  
  86. NOTE: If your "bc" program doesn't run, you may have accidentally unset
  87. its file attributes.  Try "protect s:bc +se".
  88.  
  89. **                                                                      **
  90. ** WARNING! Do not use the "CloseEd" command with programs you intend   **
  91. **          to compile using bc.  Never, never, ever!                   **
  92. **                                                                      **
  93.  
  94. Here's what should happen when you compile a program:
  95.  
  96.  1 A brief welcome message should be displayed by the compiler.
  97.  2 The BB2 TED editor screen should appear.
  98.  3 The TED welcome window should appear.
  99.  4 The window's gadget should flash, then the window should close.
  100.  5 The source code should be loaded and appear in the edit window.
  101.  6 The menus should appear, and the "COMPILE" menu should be picked.
  102.  7 The "COMPILE/RUN" or "CREATE FILE" item should be picked.
  103.  
  104.  If in "run" mode:
  105.  
  106.  8 The program should compile and run.  (Continue when program ends.)
  107.  
  108.  If in "create" mode:
  109.  
  110.  8 The "Create File" requester should appear; your file name should be
  111.    typed into, and it should be compiled and saved.
  112.  
  113.  9 If there was a compile error (e.g. syntax error), close the error
  114.    message window before proceeding.
  115. 10 A window from "bc" should appear on the TED screen with instructions.
  116.    When you close the window or press the left and right² mouse buttons:
  117. 11 The "PROJECT" menu, then "QUIT" should be selected.
  118. 12 TED, and bc, should exit.
  119.  
  120. --------------
  121.   ² Press and hold the left button, then click the right.  You may need
  122.     to do this once or twice if bc isn't listening at the exact fraction
  123.     of a second that you press them.
  124.  
  125. ·Problems·
  126.  
  127. Problems with the compile process can usually (i.e. in every case I have
  128. seen) be handled by changing your configuration file.  The most common
  129. problem (once you get the screen settings taken care of) is program size.
  130. The size of the "Load Delay Ticks" setting must be large enough for TED
  131. to have enough time to load your program.  The default setting of 100 is
  132. high enough for most small to medium sized programs if you are running off
  133. a good hard drive.
  134.  
  135. If you make your program bigger and suddenly have problems compiling, or if
  136. you notice a problem starting at around step 4-5 (from above), this is the
  137. most likely cause.  Why?  bbc sends simulated menu selection messages to
  138. TED; if the program has not yet loaded then these messages will be ignored
  139. so no compiling will take place.
  140.  
  141. Increase the number to increase the time alloted to load the source code.
  142. If your source is on floppy, increase the value _a lot_.
  143.  
  144. You may find a local configuration file valuable.
  145.  
  146. Read the included default "bc.config" file for more suggestions.  If you
  147. solve some problem heretofore undescribed in this documentation, please
  148. write to us with your problem and the solution you used so we can help
  149. others avoid your problems.
  150.  
  151. ·The Configuration File·
  152.  
  153. The included bc.config example file is a good place to start configuring
  154. your system.  You may have already made changes to it for your TED screen
  155. size.
  156.  
  157. There are three ways that bbc can get its configuration information.  When
  158. you run bc, it will tell you which method it is using in square brackets.
  159. If there is a "bc.config" file in the current directrory, it will be used.
  160. This is noted by bc with "[Using local configuration]".  If there is no
  161. local bc.config, bbc will look for one in your S: directory.  If it finds
  162. one, this is noted with "[Using global configuration]".  If it can't find
  163. one there either, it will use built-in defaults, which it notes with "[Using
  164. default configuration]".
  165.  
  166. You should avoid using the default configuration.  It won't work properly
  167. unless you are using a 640 x 200 editor screen.
  168.  
  169. Once you have set up the included bc.config for your system, you should copy
  170. it to your S: directory.  It will then become the global default so that
  171. any new project will use it.  When you need special settings for one certain
  172. project, such as when a file grows too big for your default Load Delay
  173. Ticks, copy the configuration from S:bc.config to your project directory and
  174. make changes to your local copy.
  175.  
  176. See the default configuration file for an explanation of the various
  177. settings and what they effect.  The included file is an exact match of
  178. bbc's default (internal) configuration.  You should keep it in a safe place.
  179.  
  180. ·In Closing·
  181.  
  182. We hope that this makes your life a little easier until a real command line
  183. compiler coes out.  We invite and encourage you to make changes and
  184. improvements, but remember to send us a copy (uuencoded email or mailed
  185. disk) so that we can combine everyone's improvements into a single, improved
  186. bc (you will get credit for your work).  Also feel free to send bug reports
  187. or other comments.
  188.  
  189. You can find lots of help and suggestions for making changes and
  190. improvements in the actual source code.
  191.  
  192. ·Sleep Deprivation Disclaimer·
  193.  
  194. If anything is mistyped or poorly written, or the source code unusually
  195. stupid or hard to follow, please understand that I have whipped this up
  196. in a late night non-stop programming/documentation session.  I was tired
  197. when I started, and right now I am in rather desperate need of either a
  198. coffee or a bed.
  199.  
  200. ·Copyright, etc.·
  201.  
  202. The bc software and related files and documentation ("package") are
  203. copyright © 1995 by Enchanted Blade Associates.  All rights reserved.
  204.  
  205. You are hereby given permission to distribute this package freely for
  206. non-commercial use.  You may charge a reasonable duplication/media fee for
  207. the distribution of this package (not more than $7/disk or $50/cd Canadian,
  208. including all shipping, handling, and other fees but excluding taxes).
  209. You may not charge for electronic distribution of the package (such as over
  210. the Internet or other networks, or through a bbs, or via modems), although
  211. you may charge for membership or use of that network or other entity as long
  212. as no additional charge is made for the distribution of the software.
  213.  
  214. By using this software you agree to be bound by the following licence:
  215.  
  216. 1 As this package is provided free of charge for general use, you agree that
  217. you use this package and rely on its results entirely at your own risk.  You
  218. also agree to assume full responsibility for any damages incurred by the
  219. use, misuse, or abuse of this package, except where prohibited by law.
  220. This package is provided without warranty.
  221.  
  222. 2 You agree that you may not use this package in conjunction with an illegal
  223.   or "pirated" copy of Blitz Basic 2.
  224.  
  225. 3 You agree that any changes you make to source code which you intend to
  226.   distribute or which are significant in nature will be sent along with
  227.   a short description to Enchanted Blade Associates.  This may be done in
  228.   the form of uuencoded email or a mailed diskette (address at top of
  229.   document).  In return, Enchanted Blade Associates agrees that, from
  230.   time to time, they will release a new version of the program that
  231.   incorporates all useful additions and changes into a single new version.
  232.   You will receive credit for changes made from your source code (no other
  233.   reimbursment is offered).
  234.  
  235. END OF TEXT
  236.